home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 526-550 / disk_528 / keymenu / keymenu.doc < prev    next >
Text File  |  1992-05-06  |  18KB  |  347 lines
  1.  
  2.                                 KeyMenu V1.05                       15May91
  3.  
  4.  
  5.   Purpose:
  6.  
  7.     KeyMenu is an alternative to Intuition's method of menu selection via the
  8.     keyboard. Intuition allows you to use the Right Amiga-Right Alt key
  9.     combination along with a cursor key to move the mouse pointer anywhere on
  10.     the screen. This is a simple yet flexible approach, however, if you have
  11.     ever tried to use it you probably found it to be very cumbersome for menu
  12.     selection. Keyboard shortcuts are ususally provided to invoke menu 
  13.     selections, but unless you use a particular program a lot its hard to
  14.     remember all the key combinations from one program to the next. You then
  15.     find yourself reaching for the mouse to see what menu options are
  16.     available.  
  17.  
  18.     With KeyMenu, all you need do is press and release the Right-Alt key and
  19.     the menu for the currently active window will appear. (Note: all keys
  20.     used by KeyMenu are configurable)  You can then use the cursor keys to
  21.     move through the menu as you choose.  When you have reached the menu item
  22.     you desire you can select it by pressing the return key.  If you change
  23.     your mind and decide not to select an item, the escape key can be used to
  24.     get out of the menu without making a selection.
  25.  
  26.  
  27.   Changes in version 1.05
  28.  
  29.     - now functions correctly with the new screen modes available on AmigaDos
  30.       release 2.  Note: I haven't been able to try ALL possible screen modes,
  31.       but it should work.  If you come across a mode that doesn't work PLEASE
  32.       let me know.
  33.       
  34.     - improved menu activation. With prior versions, when a menu was
  35.       activated, occasionally the menu bar would appear but the menu items
  36.       would not initially be displayed.  This has been corrected.
  37.  
  38.     - corrected a problem with subitem menus that are rendered to the left of
  39.       their associated menu item. The pointer was not always being positioned
  40.       properly.
  41.  
  42.     - now functions correctly with oversized screens, 1008x800 workbench for
  43.       example. Note: the screen MENUSNAP option in the IControl preferences
  44.       must be on for proper operation when activating a menu on an oversized
  45.       screen and the menu is not within the current view.
  46.  
  47.     - changed method used to blank Intuition's pointer. KeyMenu now turns off
  48.       sprites to remove the pointer from view rather than replacing the 
  49.       current pointer with a transparent one. This allows the blank pointer 
  50.       option to function correctly with programs that set the pointer image
  51.       when their menu is activated (ProWrite is a good example).
  52.  
  53.   Changes in version 1.04
  54.  
  55.     - added ability to configure the numeric pad keys unique to the Amiga
  56.       2000 keyboard.
  57.  
  58.     - minor correction to ignore topedge specifications in menu definitions
  59.       (as intuition does).
  60.  
  61.  
  62.   Changes in version 1.03
  63.  
  64.     - added an option to blank the intuition pointer when activating a menu.
  65.  
  66.     - KeyMenu can now coexist with 'mouse accelerator' programs without 
  67.       regard to what order you install them on the system.  KeyMenu has been
  68.       tested with dmouse, qmouse, mach and AmigaDos release 2.0 mouse
  69.       accelerators.
  70.  
  71.  
  72.   Features:
  73.  
  74.     - remembers the mouse pointer's location when a menu is activated and 
  75.       repositions the mouse at that location when the menu is exited.
  76.  
  77.     - remembers the menu item that mouse was positioned on the last time the
  78.       menu was exited. When the menu is subsequently activated, you will be
  79.       positioned on that menu item. 
  80.  
  81.     - pressing the right mouse button while KeyMenu has a menu active allows
  82.       you to override KeyMenu and take over menu operations with the mouse.
  83.  
  84.     - Intuition's method of using the keyboard to simulate the mouse is not 
  85.       hindered. In fact, the key combination of left-alt/left-amiga can be
  86.       used to simulate the left mouse button while KeyMenu has a menu active.
  87.  
  88.     - key configuration and options can be changed at any time.
  89.  
  90.     - info option allows you to determine KeyMenu's key configuration and 
  91.       option settings at any time.
  92.  
  93.     - KeyMenu is completely re-entrant (pure).
  94.  
  95.     - compatible with all formal releases of AmigaDOS. 
  96.  
  97.     - qualifier key(s) can be used in conjunction with the move keys to
  98.       move to the first/last menu, menu item or menu subitem.
  99.  
  100.     
  101.   Installation:
  102.  
  103.     Two files are required, KeyMenu and KeyMenu-Handler. KeyMenu expects the 
  104.     KeyMenu-Handler program to be on either the L: directory or the current 
  105.     directory. Other than that there are no restrictions on where these files
  106.     can be placed.
  107.  
  108.  
  109.   Usage:
  110.  
  111.     KeyMenu must be run from the CLI. The first time that KeyMenu is
  112.     executed, it installs the KeyMenu-Handler on the system, processes any
  113.     command line options that may have been specified and returns to the CLI.
  114.     There is no need to use RUNBACK to execute KeyMenu, however, it won't
  115.     hurt anything if you do. Subsequent executions can then be used to either
  116.     change KeyMenu's configuration options or to terminate KeyMenu. The
  117.     following command line options are available:
  118.  
  119.       QUIT   terminates KeyMenu.
  120.  
  121.       ?      provides help information about the command line options
  122.              available.
  123.  
  124.       -i     displays KeyMenu's current key configuration and option
  125.              settings. This option is always processed last, i.e. after any
  126.              other options that may change the configuration have been
  127.              applied.
  128.  
  129.       -b     toggles the blank intuition pointer option.  When this option is
  130.              used, KeyMenu turns off sprites whenever a menu is activated.
  131.              Sprites are turned on again when the menu is deactivated.  The
  132.              only indication that you have as to where you are in the menu
  133.              is the highlighting provided by intuition.  This can become
  134.              confusing when you select a menu that contains disabled items
  135.              because the disabled items do not highlight when you move over
  136.              them.  This option defaults to OFF.
  137.  
  138.       -t     toggles the clear RMBTRAP flag option. The RMBTRAP flag is set
  139.              by programs that wish to use the right mouse button for their
  140.              own purposes rather than dedicating it to menu operations only.
  141.              A good example of this is DeluxePaint. With DeluxePaint, you can
  142.              use the right mouse button to draw with the background color. To
  143.              do menu operations, you must move the mouse pointer into the
  144.              title bar and then press the right mouse button. When
  145.              DeluxePaint detects that the mouse has moved into the title bar,
  146.              it clears the RMBTRAP flag in its window allowing normal menu
  147.              operations to take place. This option determines what KeyMenu's
  148.              action will be when you try to activate a menu and it's
  149.              associated window has the RMBTRAP flag set. If this option is
  150.              off, KeyMenu will not activate the menu. In the case of
  151.              DeluxePaint, the mouse pointer would have to be positioned in
  152.              the title bar in order to use KeyMenu. If this option is on,
  153.              KeyMenu will clear the RMBTRAP flag in the window before it
  154.              activates the menu. This allows KeyMenu to be used with
  155.              DeluxePaint without regard to the mouse's current position. This
  156.              option should be used with CAUTION. It is impossible to predict
  157.              how any particular program will react to someone else clearing
  158.              the RMBTRAP flag. DeluxePaint doesn't seem to mind. You might
  159.              want to run KeyMenu with this option off until such time that
  160.              you find an application that uses the right mouse button and
  161.              that you really would like to use with KeyMenu. Then try this
  162.              option making sure that you have a way of recovering if the
  163.              affected application crashes.  With DeluxePaint, its debatable
  164.              just how useful KeyMenu is anyway in an application that is so
  165.              mouse oriented. This option defaults to OFF if not specified.
  166.              
  167.       -p#    specifies the priority, in decimal, that should be used when
  168.              adding KeyMenu's input handler to the input device. This option
  169.              only has effect when installing KeyMenu. You cannot change the
  170.              input handler's priority once KeyMenu is installed without
  171.              terminating KeyMenu and re-installing it. Intuition's input
  172.              handler runs at a priority of 50. KeyMenu's input handler must
  173.              be higher than Intuition's so that KeyMenu can receive the input
  174.              events before Intuition does. If this option is not specified,
  175.              KeyMenu's input handler will have a priority of 51. This value
  176.              should be ok in almost all cases. This option is provided only
  177.              for completeness and in the off chance that Intuition's input
  178.              handler priority changes in some future release of AmigaDOS. Any
  179.              value other than 51 should be chosen with great care.
  180.              
  181.       -q#    defines the qualifier key(s) that can be used in conjunction
  182.              with the move keys to move to the first/last menu, menu item or
  183.              menu subitem where # is a decimal value as follows:
  184.  
  185.                     1 - Left Shift          16 - Left Alt
  186.                     2 - Right Shift         32 - Right Alt
  187.                     4 - Caps Lock           64 - Left Amiga
  188.                     8 - Control            128 - Right Amiga
  189.  
  190.              Any combination of these keys may be specified by adding their
  191.              respective values together or this option can be completely
  192.              turned off by specifying a value of 0. When more than one
  193.              qualifier key is given, KeyMenu will honor either qualifier.
  194.              The various qualifier/move key combinations are interpreted as
  195.              follows:
  196.  
  197.                 Qualifier/Move Left  = move to the first menu in the menu
  198.                                        strip.
  199.                 Qualifier/Move Right = move to the last menu in the menu
  200.                                        strip
  201.                 Qualifier/Move Up    = move to the first menu item in the
  202.                                        current menu or subitem menu.
  203.                 Qualifier/Move Down  = move to the last menu item in the
  204.                                        current menu or subitem menu.
  205.  
  206.              For example, if the mouse is positioned on the 4th item of an
  207.              8 item menu list and a qualifier of 3 was given, pressing
  208.              either the Left-Shift/Cursor up or Right-Shift/Cursor up key
  209.              combination will cause the mouse pointer to move to the first
  210.              menu item in the list. KeyMenu defaults to the RIGHT SHIFT key
  211.              if this option is not specified.
  212.               
  213.       -a#    defines the key that will be used to activate (get into) a menu
  214.              where # is a valid key code taken from the table provided below.
  215.              This key is treated a little differently than the other keys
  216.              used by KeyMenu. To activate a menu, the activate key must be
  217.              pressed and then released without pressing any other intervening
  218.              keys. This allows key combinations involving the activate key to
  219.              be used by other programs without KeyMenu interfering. KeyMenu
  220.              defaults to the RIGHT ALT key if this option is not specified.
  221.  
  222.       -e#    defines the key that will be used to escape from (get out of
  223.              without making a selection) a menu where # is a valid key code
  224.              taken from the table below. KeyMenu defaults to the ESCAPE key
  225.              if this option is not specified.
  226.  
  227.       -s#    defines the key that will be used to select a menu item where #
  228.              is a valid key code taken from the table below. KeyMenu defaults
  229.              to the RETURN key if this option is not specified.
  230.  
  231.       -l#    defines the key that will be used to move left in the menu where
  232.              # is a valid key code taken from the table below. KeyMenu
  233.              defaults to the CURSOR LEFT key if this option is not specified.
  234.         
  235.       -r#    defines the key that will be used to move right in the menu
  236.              where # is a valid key code taken from the table below. KeyMenu
  237.              defaults to the CURSOR RIGHT key if this option is not
  238.              specified.
  239.         
  240.       -u#    defines the key that will be used to move up in the menu where #
  241.              is a valid key code taken from the table below. KeyMenu defaults
  242.              to the CURSOR UP key if this option is not specified.
  243.         
  244.       -d#    defines the key that will be used to move down in the menu where
  245.              # is a valid key code taken from the table below. KeyMenu
  246.              defaults to the CURSOR DOWN key if this option is not specified.
  247.         
  248.   
  249.     Valid key code values are as follows:
  250.  
  251.         Key Code    Key             Key Code    Key
  252.         --------    ---             --------    ---
  253.            0        `                  34       V
  254.            1        1                  35       B
  255.            2        2                  36       N
  256.            3        3                  37       M
  257.            4        4                  38       ,
  258.            5        5                  39       .
  259.            6        6                  3a       /
  260.            7        7                  3c       Numeric Pad .
  261.            8        8                  3d       Numeric Pad 7
  262.            9        9                  3e       Numeric Pad 8
  263.            a        0                  3f       Numeric Pad 9
  264.            b        -                  40       Space Bar
  265.            c        =                  41       Backspace
  266.            d        \                  42       Tab
  267.            f        Numeric Pad 0      43       Numeric Pad Enter
  268.            10       Q                  44       Return
  269.            11       W                  45       Escape
  270.            12       E                  46       Delete
  271.            13       R                  4a       Numeric Pad -
  272.            14       T                  4c       Cursor up
  273.            15       Y                  4d       Cursor down
  274.            16       U                  4e       Cursor right
  275.            17       I                  4f       Cursor left
  276.            18       O                  50       F1
  277.            19       P                  51       F2
  278.            1a       [                  52       F3
  279.            1b       ]                  53       F4
  280.            1d       Numeric Pad 1      54       F5
  281.            1e       Numeric Pad 2      55       F6
  282.            1f       Numeric Pad 3      56       F7
  283.            20       A                  57       F8
  284.            21       S                  58       F9
  285.            22       D                  59       F10
  286.            23       F                  5a       Numeric Pad (
  287.            24       G                  5b       Numeric Pad )
  288.            25       H                  5c       Numeric Pad /
  289.            26       J                  5d       Numeric Pad *
  290.            27       K                  5e       Numeric Pad +
  291.            28       L                  5f       Help
  292.            29       ;                  60       Left Shift
  293.            2a       '                  61       Right Shift
  294.            2d       Numeric Pad 4      62       Caps Lock
  295.            2e       Numeric Pad 5      63       Control
  296.            2f       Numeric Pad 6      64       Left Alt
  297.            31       Z                  65       Right Alt
  298.            32       X                  66       Left Amiga
  299.            33       C                  67       Right Amiga
  300.  
  301.  
  302.   Compatiblity:
  303.  
  304.     KeyMenu has been tested with various shareware/public domain input
  305.     handlers (such as QMouse, DMouse, Mach, PopCLI and WKeys) and with 
  306.     all versions of AmigaDos including release 2.0.
  307.     
  308.     
  309.   Source:
  310.  
  311.     KeyMenu was written in assembler using Manx Aztec 68k Assembler, version
  312.     5.0d.  Since KeyMenu is being placed in public domain, I tried to keep 
  313.     the source pretty much generic so that anyone with an assembler could
  314.     assemble it.  The addition of release 2.0 support requires that KeyMenu
  315.     be assembled with the release 2 version of the include files.
  316.  
  317.     For Manx users, KeyMenu doesn't use any of the routines from c.lib. The
  318.     library is used in the link step only to resolve the _LVO and custom 
  319.     externals. So it doesn't matter which library, c.lib or c16.lib, that you
  320.     use.
  321.     
  322.     The following source files are provided:
  323.  
  324.         keymenu.i           - include file for KeyMenu
  325.         keymenu-handler.i   - include file for KeyMenu and KeyMenu-Handler
  326.         macros.i            - misc. macros for both programs
  327.         keymenu.asm         - source for KeyMenu
  328.         keymenu-handler.asm - source for KeyMenu-Handler
  329.  
  330.  
  331.   Public Domain:
  332.  
  333.     KeyMenu and all of its associated source are public domain. You can do
  334.     what you choose with/to it. I would, however, like to know of any
  335.     problems that you encounter or enhancements that you might like to see.
  336.     Send mail to klowther on BIX if you are so inclined.
  337.     
  338.     I would like to thank the authors of DMouse, WKeys, QMouse etc. for 
  339.     making the source to their programs available. I incorporated many of
  340.     their ideas in the area of input handlers and process creation. Their
  341.     willingness to share their source code made writing this much easier. 
  342.  
  343.     A special thanks to Michael Sinz for his advice and help in testing
  344.     KeyMenu with the various screen modes available on AmigaDos Release 2.
  345.  
  346.     Ken Lowther
  347.